<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Opening the environment</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="transapp.html" title="Chapter 12.  Berkeley DB Transactional Data Store Applications" />
    <link rel="prev" href="transapp_app.html" title="Architecting Transactional Data Store applications" />
    <link rel="next" href="transapp_data_open.html" title="Opening the databases" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Opening the environment</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="transapp_app.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 12.  Berkeley DB Transactional Data Store Applications </th>
          <td width="20%" align="right"> <a accesskey="n" href="transapp_data_open.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="transapp_env_open"></a>Opening the environment</h2>
          </div>
        </div>
      </div>
      <p> 
        Creating transaction-protected applications using the
        Berkeley DB library is quite easy. Applications first use
        <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> to initialize the database environment.
        Transaction-protected applications normally require all four
        Berkeley DB subsystems, so the <a href="../api_reference/C/envopen.html#envopen_DB_INIT_MPOOL" class="olink">DB_INIT_MPOOL</a>,
        <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOCK" class="olink">DB_INIT_LOCK</a>, <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOG" class="olink">DB_INIT_LOG</a>, and <a href="../api_reference/C/envopen.html#envopen_DB_INIT_TXN" class="olink">DB_INIT_TXN</a> flags should
        be specified.
    </p>
      <p> 
        Once the application has called <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a>, it opens its
        databases within the environment. Once the databases are
        opened, the application makes changes to the databases inside
        of transactions. Each set of changes that entails a unit of
        work should be surrounded by the appropriate <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV-&gt;txn_begin()</a>,
        <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN-&gt;commit()</a> and <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN-&gt;abort()</a> calls. The Berkeley DB access
        methods will make the appropriate calls into the Lock, Log and
        Memory Pool subsystems in order to guarantee transaction
        semantics. When the application is ready to exit, all
        outstanding transactions should have been committed or
        aborted.
    </p>
      <p>
        Databases accessed by a transaction must not be closed
        during the transaction. Once all outstanding transactions are
        finished, all open Berkeley DB files should be closed. When
        the Berkeley DB database files have been closed, the
        environment should be closed by calling <a href="../api_reference/C/envclose.html" class="olink">DB_ENV-&gt;close()</a>.
    </p>
      <p>
        The following code fragment creates the database
        environment directory then opens the environment, running
        recovery. Our <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> database environment handle is declared to
        be free-threaded using the <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag, and so may be
        used by any number of threads that we may subsequently create.
    </p>
      <a id="prog_transapp1"></a>
      <pre class="programlisting">#include &lt;sys/types.h&gt;
#include &lt;sys/stat.h&gt;

#include &lt;errno.h&gt;
#include &lt;stdarg.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;string.h&gt;
#include &lt;unistd.h&gt;

#include &lt;db.h&gt;

#define    ENV_DIRECTORY    "TXNAPP"

void  env_dir_create(void);
void  env_open(DB_ENV **);
...

int
main(int argc, char *argv[])
{
    extern int optind;
    DB_ENV *dbenv;
    int ch;

    while ((ch = getopt(argc, argv, "")) != EOF)
        switch (ch) {
        case '?':
        default:
            usage();
        }
    argc -= optind;
    argv += optind;

    env_dir_create();
    env_open(&amp;dbenv);
    ...

    return (0);
}

...

void
env_dir_create()
{
    struct stat sb;

    /*
     * If the directory exists, we're done.  We do not further check
     * the type of the file, DB will fail appropriately if it's the
     * wrong type.
     */
    if (stat(ENV_DIRECTORY, &amp;sb) == 0)
        return;

    /* Create the directory, read/write/access owner only. */
    if (mkdir(ENV_DIRECTORY, S_IRWXU) != 0) {
        fprintf(stderr,
            "txnapp: mkdir: %s: %s\n", ENV_DIRECTORY, strerror(errno));
        exit (1);
    }
}

void
env_open(DB_ENV **dbenvp)
{
    DB_ENV *dbenv;
    int ret;

    /* Create the environment handle. */
    if ((ret = db_env_create(&amp;dbenv, 0)) != 0) {
        fprintf(stderr,
            "txnapp: db_env_create: %s\n", db_strerror(ret));
        exit (1);
    }

    /* Set up error handling. */
    dbenv-&gt;set_errpfx(dbenv, "txnapp");
    dbenv-&gt;set_errfile(dbenv, stderr);

    /*
     * Open a transactional environment:
     *    create if it doesn't exist
     *    free-threaded handle
     *    run recovery
     *    read/write owner only
     */
    if ((ret = dbenv-&gt;open(dbenv, ENV_DIRECTORY,
        DB_CREATE | DB_INIT_LOCK | DB_INIT_LOG |
        DB_INIT_MPOOL | DB_INIT_TXN | DB_RECOVER | DB_THREAD,
        S_IRUSR | S_IWUSR)) != 0) {
        (void)dbenv-&gt;close(dbenv, 0);
        fprintf(stderr, "dbenv-&gt;open: %s: %s\n",
            ENV_DIRECTORY, db_strerror(ret));
        exit (1);
    }

    *dbenvp = dbenv;
}</pre>
      <p>
        After running this initial program, we can use the
        <a href="../api_reference/C/db_stat.html" class="olink">db_stat</a> utility to display the contents of the environment
        directory:
    </p>
      <pre class="programlisting">prompt&gt; db_stat -e -h TXNAPP
3.2.1   Environment version.
120897  Magic number.
0       Panic value.
1       References.
6       Locks granted without waiting.
0       Locks granted after waiting.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Mpool Region: 4.
264KB   Size (270336 bytes).
-1      Segment ID.
1       Locks granted without waiting.
0       Locks granted after waiting.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Log Region: 3.
96KB    Size (98304 bytes).
-1      Segment ID.
3       Locks granted without waiting.
0       Locks granted after waiting.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Lock Region: 2.
240KB   Size (245760 bytes).
-1      Segment ID.
1       Locks granted without waiting.
0       Locks granted after waiting.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Txn Region: 5.
8KB     Size (8192 bytes).
-1      Segment ID.
1       Locks granted without waiting.
0       Locks granted after waiting.</pre>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="transapp_app.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="transapp.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="transapp_data_open.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Architecting Transactional Data
        Store applications </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Opening the databases</td>
        </tr>
      </table>
    </div>
  </body>
</html>
